Name Requests Clicks
0 1Adventure Outfitters 444 444 2 1Clocktower 555 555 4 1Trey Research 666 666 1 1Volcano Coffee Company 777 777 99 1Volpe Caffine Cartel 888 888
Last updated on 8/23/00

ListSheet Widget

/widgets/listHTC/listsheet.htc

The ListSheet is the workhorse of a selection page. It displays a selectable list in a number of formats, as well as enabling paging and sorting. Columns are displayed in the order that they are specified in the meta-data.

loading widget, please wait...

Event log:


events

onError
fires on error (when m_bDebug = true in HTC, shows alert as well)

event object properties

window.event.error String. Returns error detail.

OnRowSelect
fires when a row selected

event object properties

window.event.XMLrecord XMLNode. The XML <record> node for the selected row

OnRowUnselect
fires when a row unselected

event object properties

window.event.XMLrecord XMLNode. The XML <record> node for the unselected row

OnAllRowsSelect
fires when all rows selected
OnAllRowsUnselect
fires when all rows unselected
OnGroupOpen
fires when a group row opened

event object properties

window.event.XMLrecord XMLNode. The XML <record> node for the opened group row

OnHeaderClick
fires when column header is clicked

event object properties

window.event.sortcol String. The column id for the column whose header was clicked
window.event.sortdir String. The direction to sort, one of: "asc", "desc"

OnNewPage
fires when back or next buttons clicked or page number changed

window.event.page Positive integer. The page number to display

methods

elListSheet.selectAllRows()
selects all rows

parameters

none

return value

none

elListSheet.unselectAllRows()
unselects all rows

parameters

none

return value

none

bSuccess = elListSheet.reload(sOp, sArgs)
reloads the list using an operation configured in meta-xml. Note that explicit calls to reload will automatically unselect all items in the list. When 'page' and 'sort' operations are done internally unselect is not called. Usually, you will want to also reset the page number to 1 for multipage lists when calling reload.

parameters

sOp is an operation child node name in meta-xml. The child nodes' id corresponds to a form in the document whose ACTION = the post page and whose elements will be sent along with any other arguments below

sArgs is a list of URL-encoded page arguments to pass to the post page. Note: arguments sent by default: "op", "page" (for "newpage" op), "column" and "direction" (for sort op), "xmlrecord" (for sublist op)

return value

Boolean. Represents success. True = document retreived, with no errors and at least one record.

container attributes (set on element using ListSheet behavior)

DataXML xml data (from a recordset) data-island id. Usually in the format:
	<document>
		<record>
			<fieldId1>fieldValue1</fieldId1>
			<fieldId2>fieldValue2</fieldId2>
			...
		</record>
		...
	</document>
Hierarchical lists have data in either a 2-teir format:
	<document>
		<record>
			<fieldId1>fieldValue1</fieldId1>
			<fieldId2>fieldValue2</fieldId2>
			...
			<record>
				<fieldId1>fieldValue1</fieldId1>
				<fieldId2>fieldValue2</fieldId2>
				...
			</record>
		</record>
		...
	</document>
... or a 3-teir format:
	<document>
		<record>
			<fieldId1>fieldValue1</fieldId1>
			<fieldId2>fieldValue2</fieldId2>
			...
			<record>
				<fieldId1>fieldValue1</fieldId1>
				<fieldId2>fieldValue2</fieldId2>
				...
				<record>
					<fieldId1>fieldValue1</fieldId1>
					<fieldId2>fieldValue2</fieldId2>
					...
				</record>
			</record>
		</record>
		...
	</document>
MetaXML xml meta-data data-island id

scriptable properties

set xmlList = elListSheet.XMLlist
Read-only. XML document node containing the list. Each row is in a child <record> node containing a sub-node for eachy field/column. Select columns return two sub-nodes; one with the name of the column containing the underlying value and one named colid_displayvalue containing the display name for that value.
bValue = elListSheet.page
elListSheet.page = bValue
Read-write. Gets or sets current page number in page controls. Note: setting page does not fire the onNewPage event or fetch a new list.
bValue = elListSheet.recordcount
elListSheet.recordcount = bValue
Read-write. Gets or sets current recordcount and recalculates page controls. Setting recordcount to -1 displays page controls with last page button disabled. setting to 0 (zero) will hide the page controls

list types:

  1. flat list: id2 and id3 attributes in the <global> node are not used. The <subobject> collection node is not used.
  2. homogeneous grouped list: grouped lists where columns of all group and detail rows are the same; two types:
    1. 2-level grouped item list: id2 is used to map columns in the second level <record> nodes to columns in the list. The <subobject> collection node is not used.
    2. 3-level grouped item list: id2 and id3 are used to map columns in the second and third level <record> nodes to columns in the list. The <subobject> collection node is not used.
  3. heterogeneous grouped list: grouped lists group rows and detail rows are different. There are two types:
    1. list style (looks like an embedded ListSheet) has multiple records per sub-object: The <subobject> collection node is used to describe the columns from the second level <record> nodes that will be displayed in the sub-object table. id2 and id3 in the top level <column> nodes are not used.
    2. properties style (looks like an embedded read-only EditSheet) has a single record per sub-object: The <subobject> collection node is used to describe the columns from the second level <record> nodes that will be displayed in the sub-object table. id2 and id3 in the top level <column> nodes are not used.

meta-xml

KEY:     <NodeTag>     <RepeatingNodeTag*>     @attribute

sample

<xml id='lsMeta'>
  <listsheet>
    <global curpage='2' pagesize='20' recordcount='4387' selection='multi' />
    <columns>
       <column id='id' id2='id' hide='yes'></column>
       <column id='name' id2='type' sortdir='asc' width='25'>Name</column>
       <column id='events' id2='events' width='15'>Events</column>
       <column id='requests' id2='requests' width='15'>Requests</column>
       <column id='clicks' id2='clicks' width='15'>Clicks</column>
       <column id='clickpercent' id2='clickpercent' width='15' format='float'>Click %</column>
       <column id='sold' id2='sold' width='15' format='float'>Sold</column>
    </columns>
    <operations>
	   <newpage formid='newpageform'/>
    </operations>
  </listsheet>
</xml>